package com.docmgmt.mvp.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.docmgmt.mvp.dto.AiChatRequest;
import com.docmgmt.mvp.dto.AiChatResponse;
import com.docmgmt.mvp.entity.AiDialogEntity;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;

import java.util.List;

/**
 * AI服务接口
 *
 * v3.0架构：支持4种查询范围（global/kb/folder/file）+ 三级隐私过滤（public/shared/privacy）
 *
 * @author Dora
 */
public interface AiService extends IService<AiDialogEntity> {

    /**
     * AI问答（v3.0版本：权限感知 + 4种范围）
     *
     * 4种问答范围：
     * 1. global: 全局文档（带隐私级别过滤：public所有人可见 + shared同部门可见 + privacy仅创建者可见）
     * 2. kb: 指定知识库（需检查权限）
     * 3. folder: 指定文件夹（递归子文件夹，需检查权限）
     * 4. file: 单个文件（需检查权限）
     *
     * @param request 问答请求
     * @param userId  用户ID
     * @return 问答响应
     */
    AiChatResponse chat(AiChatRequest request, Long userId);

    /**
     * AI问答（SSE流式响应版本）
     *
     * 适用于需要实时返回AI回答的场景，提升用户体验
     *
     * @param request 问答请求
     * @param userId  用户ID
     * @return SSE Emitter
     */
    SseEmitter chatStream(AiChatRequest request, Long userId);

    /**
     * 获取用户对话历史
     *
     * @param userId 用户ID
     * @param limit  返回数量限制
     * @return 对话历史列表（按时间倒序）
     */
    List<AiDialogEntity> getDialogHistory(Long userId, Integer limit);

    /**
     * 删除对话历史（软删除）
     *
     * @param userId   用户ID
     * @param dialogId 对话ID
     */
    void deleteDialog(Long userId, Long dialogId);

    /**
     * 清空用户所有对话历史（软删除）
     *
     * @param userId 用户ID
     */
    void clearAllDialogs(Long userId);
}
